Créer un blog statique Hugo de A à Y

09/03/2018 - ~13mins www tuto hugo Dernière mise à jour le : 15/05/2019

Je vois que ces derniers temps Hugo commence à attirer de nouvelles personnes. Du coup, pourquoi pas vous proposer un article un peu plus en profondeur sur ce que j'ai compris d'Hugo. Je vous ai déjà fait un retour sur mon utilisation d'Hugo mais là ça va plus être sous le capot.

Je vais vous montrer comment faire ses premiers pas pour se monter un blog simple comme le mien avec un thème fait maison.

Facts

Tout d'abord voilà un ensemble de facts que j'ai accumulé.

•.Hugo n'est pas un moteur de blog mais un générateur de site web statique. Vous pouvez en faire autre chose qu'un blog. Et du coup par défaut il ne fait pas forcément un blog. Par défaut d'ailleurs il ne fait pas grand chose comme vous le verrez.
•.Hugo fonctionne avec des sections. Vous pouvez avoir une section blog, une autre pour des articles, encore une autre pour des recettes de cuisines et une dernière pour les livres que vous avez lus. Chaque section peut être “indépendante” dans le sens où vous allez appliquer un template différent.
•.Un thème Hugo n'est pas juste une couche graphique. Un thème Hugo peut définir la structure de votre site. Il est difficile de faire quelque chose non prévu par le thème sans le retoucher. Et changer de thème une fois que votre site en utilise un particulier ne se fera pas en un claquement de doigts.
•.Créer un thème peut être un peu ardu la première fois si vous n'avez jamais pondu de html/css.
•.Créer un thème est relativement aisé, surtout si l'on repars d'un thème existant que l'on tord jusqu'à décider de repartir de 0 avec ce que l'on veux exactement.
•.Hugo gère super bien les sites multi-langues pour peu que vous traduisiez le contenu.
•.Migrer de Wordpress à Hugo n'est pas chose aisée.
•.Comme tous les générateurs de sites statiques, Hugo pond des sites facilement hébergeable, très performants et sans soucis de sécurité.
•.Hugo a des mises à jour très régulièrement qui apporte de nouvelles fonctionnalités souvent dispensables. Pas la peine de rusher les mises à jour : il n'y a pas de risque de faille de sécurité exploitable depuis votre site ouaib.
•.Hugo fournit des messages d'erreurs globalement assez clair si vous vous lancer dans la création d'un thème. Il vous indiquera généralement les caractères qui lui posent soucis (tel fichier, telle ligne).
•.La doc d'Hugo est super bien foutue. Toutes les fonctions sont documentées, souvent avec des exemples, parfois même des vidéos.
•.La collection de thêmes est plutôt conséquente. Méfiez-vous, beaucoup de thème utilisent des fonts externes, des JS externes, du facebook/twitter…
•.Hugo génère par défaut un flux RSS tronqué. Il est aisé de trafiquer le flux RSS pour qu'il soit complet, ne contiennent que les X derniers articles…
•.Hugo possède un serveur web intégré vous permettant de tester votre site ouaib en live quand vous faites des modifs. Il peut même vous emmener directement sur la page ayant été modifiée automatiquement dès que vous changer un fichier.

Bon après ces quelques remarques globales, attaquons nous à la création d'un blog basique ainsi que son thème.

Créer la structure de votre site

Bon, sur votre machine personnelle, on va créer un dossier blog et maintenant tout se fera à partir de ce dossier. hugo new site ./ Et voilà votre dossier peuplé de nouveaux dossiers.

•.archetypes : contient les éléments qui seront automatiquement rajouté quand vous créerez un nouvel article
•.config.toml : fichier texte où se trouve la configuration de votre site
•.content : contiendra vos articles
•.layouts : contient les squelettes des pages qui seront générés
•.static : contiendra les données statiques ajoutées à votre site (les images,js, css,…)
•.themes : où vous pourrez mettre les différents thèmes Hugo

Créer un article

Afin de pouvoir expérimenter au plus vite, on va déjà créer un article bidon pour votre site.

Au préalable, on va créer une section blog : mkdir content/blog. Désormais tous vos articles de blog on les rangera dans ce dossier.

Créons l'article : hugo new blog/welcome.md . La chose à prendre en compte c'est que vous ne placez pas explicitement votre nouvel article dans content, il le fait de lui même. Quand vous utilisez la commande hugo new, ça sera automatiquement dans content.

Maintenant ajoutons du contenu à l'article : vim content/blog/welcome.md Et là vous devriez vous retrouver avec déjà quelques lignes dans votre article.

---

title: "Welcome"

date: 2018-03-07T12:15:24+01:00

draft: true

---

Ces données proviennent en fait du fichier archetypes/default.md fournit par défaut. Dans le jargon on appelle ça le frontmatter. Tout ce qui se trouve entre les --- (ou +++ en fonction du format). Donc par défaut le titre de votre article sera tiré du nom du fichier donné par la commande hugo new. La date correspondra à la création du fichier et par défaut votre fichier est à l'état de brouillon. Par défaut, Hugo ne génère pas les pages à l'état de brouillon. Pour la suite, mettez draft: false.

Vous pouvez rédiger en dessous votre article en utilisant la syntaxe MarkDown.

Bon après avoir ajouté un peu de contenu à cet article on va commencer les choses sérieuses : générer une page web !

Configuration

Donc pour générer votre site web, il vous suffit de taper : hugo

| EN

+-------------------+----+

C'est tout de même mignon ce petit tableau récapitulatif ! Bon alors premièrement, votre site est probablement pas en anglais donc va falloir lui dire qu'il se goure.

Allez, voyons le config.toml

baseURL = "http://adresse.de.votre.site/"

languageCode = "fr-fr"

DefaultContentLanguage = "fr"

title = "le nom de votre site"

On pourra se contenter de ces réglages pour le moment. Et du coup si vous relancez la commande hugo vous verrez que vous générez désormais du français !

Paramètres fait maison

Hugo n'est pas chiant, vous pouvez rajouter des paramètres qui vous serviront pour votre thème, en plus des paramètres existants. Pour cela il suffit de faire ça sous la forme :

[params]

mon_param_a_moi = "machin"

Vous pourrez les utiliser via .Site.params.mon_param_a_moi mais on verra ça mieux un peu plus loin.

Génération

Après avoir généré votre site, vous devriez voir un dossier public contenant quelques sous-dossiers et fichiers :

3 directories, 5 files

La section blog a été créé avec dedans un index.xml, le dossier categories est automatiquement créé et contiendra les différentes catégories de vos articles de blog. sitemap.xml est le sitemap de votre site automatiquement généré par Hugo pour vous permettre d'être bien vu par les moteurs de recherche. tags est à l'image de categories et sera rempli tout seul au fur et à mesure. Tous les index.xml sont des flux RSS.

Mais du coup … je comprends pas … elles sont où les pages web ?

Pour l'instant vous n'avez pas donné d'instruction à Hugo sur la façon de générer les pages. Du coup en bon fainéant… il a rien foutu.

Layouts

Pour les moins anglophones, le layout est l'agencement des pages. En gros c'est le squelette HTML de vos pages que vous allez demander à Hugo de remplir avec le Markdown de vos articles.

On va commencer par le minimum absolu.

Dans layouts/index.html :

Je vous avais prévenu c'est vraiment peu. Maintenant on régénère via hugo et on voit qu'on a désormais public/index.html qui existe. Et comme par hasard il contient exactement la même chose que définie dans le layouts/index.html.

Ajoutons la magie d'Hugo : Toujours dans layouts/index.html :

<html>

<body>

<h1>{{ .Title }}</h1>

</bdy>

</html>

Et maintenant refaites un ptit coup de hugo et observez votre nouvel public/index.html

Voilà, votre tout premier résultat tangible. Voyons ce qu'il s'est passé.

{{ range .Data.Pages }} indique à Hugo d'itérer sur toutes les pages de contenu que vous avez créé. Donc dans notre cas uniquement le fichier content/blog/welcome.md. Il s'agit d'une boucle qui s'exécutera pour chacun des items jusqu'à la fermeture qu'est {{ end }}.

Et dans cette boucle on récupère le {{ .Title }} qui est donc le title que vous avez mis dans le frontmatter de l'article. Et enfin {{ .Content }} est le rendu du MarkDown se trouvant hors du frontmatter de l'article.

C'est pas bien compliqué.

Partials

Hugo vous permet d'utiliser des morceaux de HTML que vous allez pouvoir inclure par la suite.

mkdir layouts/partials et ensuite éditons layouts/partials/header.html

<!DOCTYPE html>

<head>

<title>{{ .Title }}</title>

</head>

{{ .Site.Language.Lang }} sera remplacé par la langue de la page en question. Si vous avez la même page dans différentes langues cette variable sera ajustée en fonction.

{{ .HugoGenerator}} sera remplacé par la version de votre ptit Hugo.

Plusieurs fois vous trouverez {{ .Site.BaseURL }} c'est la variable définie dans config.toml à la racine de votre site.

Bref maintenant yapuka inclure ça dans votre layout : layouts/index.html en ajoutant juste

Un ptit coup de hugo et on observe le résultat. Le partial est inclus dans votre page web avec ses variables qui sont bien remplacées. Il nous reste encore un détail à voir et vous serez à même de vous débrouillez comme de grandes personnes.

List/Single pages

Hugo repose sur deux principaux types de pages. Les list pages et les single pages. Les single pages sont les pages affichant un item d'une section (dans notre cas un article de blog). Les list pages sont les pages listant les items d'une section (tous les articles du blog).

Jusqu'à présent, dans notre exemple, nous n'avons travaillé que la home page du site en bidouillant layouts/index.html. On va donc générer la page pour un article de blog.

mkdir layouts/blog puis éditons layouts/blog/single.html

<body>

<h1><a href="{{ .RelPermalink }}">{{ .Title }}</a><h1>

<p class="meta">{{ .Date.Format "02/01/2006" }}</p>

Bon ça reste assez simple (notez comme j'amène de nouveaux éléments que progressivement…). {{ .RelPermaLink }} est le lien vers l'article. {{ .Date.Format }} lit le paramètre date de l'article et le met au format "02/01/2006". J'avoue que cette désignation est assez étrange mais bon vous trouverez ici plus d'explication sur les formats possibles.

Impatients de voir le résultat ? hugo puis là vous aurez encore plus de fichiers \o/

public

├── blog

│ ├── index.xml

│ └── welcome

│ └── index.html

├── categories

│ └── index.xml

├── index.html

├── index.xml

├── sitemap.xml

└── tags

└── index.xml

4 directories, 7 files

Vous avez maintenant un dossier blog avec à l'intérieur un index.html qui se trouve être votre single page de l'article. Vous y trouverez comme prévu ce que vous avez mis dans layouts/blog/single.html.

Il ne reste donc plus qu'à faire la list page de la section blog :-)

layouts/blog/list.html

<body>

<main>

<h1>Mon blog moche</h1>

<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>

</header>

</article>

</main>

</body>

</html>

Peu de nouveauté. {{ .Summary }} ne vous sortira pas l'article en entier mais juste le début. Une fois votre site généré vous aurez désormais un public/blog/index.html.